home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / wais / README < prev    next >
Text File  |  1995-05-09  |  10KB  |  256 lines
  1. README:    WAIS Unix release 8 b5                Sun May 10 1992
  2.  Harry Morris                     Thinking Machines Corp
  3.  Brewster Kahle 
  4.  Jonathan Goldman
  5. ------------------------------------------------------------------------
  6.  
  7. WARRANTY DISCLAIMER
  8.  
  9. This software was created by Thinking Machines Corporation and is distributed 
  10. free of charge.  It is placed in the public domain and permission is granted 
  11. for anyone to use, duplicate, modify and redistribute it.
  12.  
  13. Thinking Machines Corporation provides absolutely NO WARRANTY OF ANY KIND with
  14. respect to this software.  The entire risk as to the quality and performance 
  15. of this software is with the user.  IN NO EVENT WILL THINKING MACHINES 
  16. CORPORATION BE LIABLE TO ANYONE FOR ANY DAMAGES ARISING OUT THE USE OF THIS
  17. SOFTWARE, INCLUDING, WITHOUT LIMITATION, DAMAGES RESULTING FROM LOST DATA OR
  18. LOST PROFITS, OR FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES.
  19.  
  20. ------------------------------------------------------------------------
  21.  
  22. First, if you are trying to figure out how to install or build this
  23. software, take a look at the file "INSTALLATION", in this directory.
  24.  
  25. The Wide Area Information Server (WAIS) Project is an experiment,
  26. automating the search and retrieval of many types of electronic information
  27. over wide area networks.  The success of this project depends on the
  28. formation of a large number of "Information Servers": computers that know
  29. how to answer questions over a network.  To help catalyze this market,
  30. Thinking Machines and other organizations are giving away protocol
  31. specifications and source code.  To find out more about the project, please
  32. read doc/wais-concepts.txt.  New releases are announced on the mailing list
  33. wais-interest@think.com, discussion of WAIS issues happens on
  34. wais-discussion@think.com.  To be added to these lists, please send a note
  35. to wais-interest-request@think.com and/or wais-discussion-request@think.com.
  36.  
  37. The remainder of this file contains:
  38.     I.    Installation notes.
  39.     II.    What's in this package and how to use it.
  40.     III.    Random notes.
  41.  
  42.  
  43.  
  44.  
  45. I. Installation notes:
  46.  
  47. This package has been written for ANSI-C.  GNU CC and non-ANSI cc's are
  48. supported by adding a bunch of library routines that were not present.  It
  49. has been run on a VAX, Sun-3, Sun-4, and NeXT, System V, gcc, cc, ThinkC.
  50. Pieces have been run on VMS.  We are interested in promoting the
  51. portability of this code.  If you run into problems, please help by
  52. reporting (or fixing) bugs.
  53.  
  54. One thing to note for the Emacs interface on the NeXT: In ui/wais.el lines
  55. 126-130:
  56.  
  57.     (let (
  58.       ;; this doesn't work on the NeXT.  Comment out this line.
  59.       (process-connection-type nil)
  60.       )
  61.  
  62. Be sure to comment out the local variable on the NeXT.
  63.  
  64. Since you are reading this file, you must have been able to untar the
  65. distribution.  There is a Makefile in the same directory as this file.
  66. Take a look at it and determine if the various configurations definitions
  67. are appropriate for your system, then run "make".
  68.  
  69. II.  What's in this package and how to use it
  70.  
  71. This package contains a sample toolkit for:
  72.  
  73.   1. creating servers:  waisindex and waisserver.
  74.   2. communicating:     Z39.50 and WAIS protocol software.
  75.   3. clients:           X-windows, GNU Emacs, and shell interfaces.
  76.  
  77. This package is distributed as a UNIX tar file.  You should have the
  78. following directories:
  79.  
  80. top = wais-8-b5
  81.  
  82. in top:
  83.  
  84. Makefile    - a top-level Makefile to build the entire system
  85. README        - this file
  86. INSTALLATION    - some instructions on how to build this software
  87. RELEASE-NOTES    - current state of the software, including changes
  88.           from the last release
  89. bin/        - where compiled executables will go
  90. buildtar.sh*    - a script for building this distribution
  91. doc/        - all documentation
  92. ir/        - the WAIS toolkit, indexer and server code
  93. survey.txt    - to be filled out with your comments
  94. ui/        - some example user interfaces, including the GNU Emacs and
  95.           shell interfaces
  96. wais-sources/    - example sources, including the directory of servers
  97. x/        - an X11R4 client
  98. z39-50-wais.mms - a "VMS" style makefile
  99. *.xmail        - some GNU Emacs RMAIL files of modifications some people
  100.           have done in order to compile this on their machines
  101.  
  102.  
  103. Unix-style Man pages are in the doc directory. An interface for the Apple
  104. Macintosh is available separately.
  105.  
  106. There are three programs that comprise the core of this WAIS software:
  107.  
  108. WAISINDEX: This indexer is a simple Information Retrieval engine that
  109.  indexes every word of the input files, creating an "inverted file index".
  110.  This allows keyword searching based on the full text of documents.  The
  111.  indexer uses the file system in a straightforward and conservative manner
  112.  (it is written in ANSI C) and so it should be quite portable.  A number of
  113.  "filters" have been written to handle common file formats.  Making new ones
  114.  is easy, see the file ircfiles.c for examples and instructions.  
  115.  
  116. WAISSERVER: Listens to a TCP port for questions (Z39.50 packets) and uses
  117.  the appropriate index to answer the question.  This is pretty stable.
  118.  Waisserver may be run as a standalone server, or it can be run from inetd.
  119.  Look at the MAN page for waisserver for example inetd.conf entries.
  120.  
  121. WAISSEARCH: A simple shell user interface for sending questions to
  122.  wais servers.  Additionally, there are X and Gnu Emacs interfaces included,
  123.  which you will probably find more convenient to use.
  124.  
  125.  
  126. -------------------------
  127. CREATING A WAIS DATABASE
  128. -------------------------
  129.  
  130. To create an index for your own private use:
  131.  
  132. First index some files:
  133.     waisindex -d ~/wais-sources/rmail -t rmail RMAIL
  134. then make a search request:
  135.     waissearch -d ~/wais-sources/rmail "What is WAIS?"
  136.  
  137. Once the index is made, you can also search it using the xwais or
  138. Gnu Emacs interfaces.  See the documentation files for further information.
  139.  
  140.  
  141. To create a server for everyone to use:
  142.  
  143. To advertise the availability of your data, you can send in an entry to the
  144. Directory of Servers, a server running at an easily accessible
  145. location (quake.think.com).  The following command will index your-files,
  146. and register the index with the Directory of Servers.  Needless to say,
  147. this should be done with care.
  148.  
  149.     waisindex -export -register your-files
  150.  
  151. You may have noticed a database was created when you built this software:
  152. the wais-docs database.  Take a look at the Makefile in the docs directory
  153. for another example of how to build a database.
  154.  
  155. ---------------------
  156. RUNNING A WAIS SERVER
  157. ---------------------
  158.  
  159. There are two options for running the server: 
  160.  
  161. 1. as a standalone process,
  162. 2. as a daemon under inetd.
  163.  
  164. To run the standalone server simply type "waisserver -p <port-number>" at a
  165. prompt, where port-number is a TCP port that the server will use to handle
  166. client connections.  Most UNIX systems will only allow the super user to
  167. use ports less than 1024.
  168.  
  169. To run under inetd, you must have the z3950 service defined and a line in
  170. your inetd configuration file that tells inetd what to do when a connection
  171. is received on the z3950 port.  On most systems this means adding the z3950
  172. service to /etc/services or the NIS (used to be called YP) database as
  173. follows:
  174.  
  175. z3950        210/tcp                # Z39_50 protocol for WAIS
  176.  
  177. and in /etc/inetd.conf:
  178.  
  179. z3950 stream tcp nowait waisp <top>/bin/waisserver waisserver.d -e <top>/server.log -d <top>/wais-sources
  180.  
  181. Note the user field in this example is waisp, which is the userid the
  182. daemon will be run under. This userid is rarely present, and can be
  183. replaced by something appropriate for your site (typically UUCP).  The
  184. directory <top> is as defined above (this directory), and the user
  185. specified in the above line must have read/write permission to the
  186. directory specified in the -d argument.  The -e argument is a file the
  187. daemon will use to log it's output, which must be writable too.  This is
  188. explained in more detail in the man page on waisserver.
  189.  
  190. --------------
  191. TESTING IT OUT
  192. --------------
  193.  
  194. To test things out, first insure that you can do something with the
  195. waissearch program:
  196.  
  197. % cd <top>/wais-sources
  198. % ../bin/waissearch -d wais-docs wais
  199.  
  200. You should get a bunch of results.
  201. Now try to talk to the directory-of-servers:
  202. % ../bin/waissearch -h quake.think.com -p 210 -d directory-of-servers source
  203.  
  204. You should get a bunch more results.  This requires an internet connection,
  205. so if you can telnet to quake.think.com, it should work.
  206.  
  207. Now you can try your server:
  208.  
  209. % ../bin/waissearch -h <your-host> -p <port-number> help where <your-host>
  210. is the name of the machine you are running the server on, and <port-number>
  211. is the port specified when starting the server (or the z3950 port if run
  212. under inetd).  This should return at least two results: the source
  213. description file INFO.src and a catalog of what your server is serving.
  214.  
  215. You can then try the other user interfaces included in this release.
  216.  
  217. ----------------------------------------------------------------------
  218. For instructions on using the Gnu Emacs interface to access remote servers,
  219. see the file ui/wais.el.
  220.  
  221.  
  222.  
  223.  
  224. III. Random Notes
  225.  
  226. - The version of Z39.50 contained herein is for inspection only.  It is based 
  227.   on the obsolete 1988 version.  It will be replaced with an implementation
  228.   of ISO Z39.50 (when it stabilizes).  These protocols are not compatible, 
  229.   although every effort will be made to minimize the conversion effort. 
  230.     
  231. - The best way to learn the use of the Z39.50 library is to study
  232.   the example code in ir.c (for a server) and ui.c and ui (for a client).
  233.   
  234. - The IR engine will undergo further enhancements.
  235.   
  236. - WAIStation is an example Mac program using this protocol.  This is
  237.   provided "as is" as an application that can connect over the phone or
  238.   TCP/IP.  It is available separately, in source code form.  Write for
  239.   details.
  240.  
  241. - Have fun and let us know what you think.  Much of this code needs
  242.   cleanup, we apologize for the present formatting.... The next 
  243.   version will be beautified, clarified, polished, and all.  If you
  244.   have any questions or find any bugs, Don't hesitate to write.
  245.  
  246.       Harry Morris
  247.       Morris@Think.COM
  248.  
  249.     Brewster Kahle
  250.     Brewster@Think.COM
  251.           
  252.     Jonny Goldman
  253.     Jonathan@Think.COM
  254.  
  255.       (617) 876-1111
  256.